home *** CD-ROM | disk | FTP | other *** search
/ Java 1996 August / Java - Summer 1996.iso / sundist / README < prev    next >
Text File  |  1996-07-22  |  16KB  |  398 lines
  1.                  README: The Java Developers Kit
  2.  
  3.  
  4. This 1.0 BETA release of the Java Developers Kit (JDK) lets
  5. you write applets that conform to the 1.0 Java applet API.  
  6.  
  7. About the Beta JDK
  8. -----------------------------------------
  9.  
  10.     Welcome to the Beta release of the Java Development Kit for Macintosh.
  11.     The JDK is used specifically to allow people to write Java applets for
  12.     use in a Java aware browser, such as Netscape Navigator¬ or Sun's HotJava,
  13.     using the 1.0 Java Applet API.  You can not build standalone
  14.     applications with this version of the JDK.
  15.  
  16.     The JDK incorporates the Java virtual machine as a shared library,
  17.     along with the AWT (Abstract Window Toolkit), Networking, and
  18.     Multimedia libraries.  (NOTE: the MMedia library is not yet
  19.     available, as of this release..)
  20.  
  21.  
  22. About the distribution
  23. -----------------------------------------
  24.  
  25.     In order to make the release easier to use on the Macintosh, we have used a
  26.     slightly different folder hierarchy than for the other JDK releases. For example,
  27.     a "bin" folder doesn't make much sense on the Mac, so we moved the executable
  28.     applications to the top level folder. Naturally, the content remains the same.
  29.  
  30.  
  31. Supported Platforms
  32. -----------------------------------------
  33.  
  34.     The JDK requires a Macintosh running System 7.5 with 8 megabytes of
  35.     real memory and 7 megabytes of hard disk space.  The JDK is fully
  36.     compatible with virtual memory and most third party extensions.
  37.  
  38.  
  39. JDK Contents
  40. -----------------------------------------
  41.  
  42.     README: This document
  43.     
  44.     COPYRIGHT: You must read this before using the JDK. Please make sure
  45.         you understand the copyright and license information before using
  46.         this release.
  47.     
  48.     Java Compiler: The Java Byte Code Compiler.
  49.     
  50.     AppletViewer: An application for testing and running applets.
  51.     
  52.     Classes: A database of class files used the compiler & applet viewer. 
  53.         This file must be present in the same directory as those
  54.         applications. (NOTE: may change later on!)
  55.     
  56.     Java.shlb: The Java runtime share library for PowerPC.  (NOTE: for
  57.         now, must be in the same directory as the applications, but it
  58.         is not needed for 68k only installations.)
  59.     
  60.     lib: support for the runtime and compiler.  (NOTE: for
  61.         now, must be in the same directory as the applications, and at
  62.         least "javac.properties" must be present for 68k only installations.)
  63.     
  64.     Sample Applets:  An assortment of applets, with source code, for you
  65.         to copy and learn from.  This is the best place to start if you're
  66.         new to applet development.
  67.  
  68.     API User's Guide.html: Documentation on the Java Class APIs, presented in
  69.         HTML format.
  70.         
  71.     API Documentation: Documentation in .html format.
  72.  
  73.  
  74. What is the final applet API?
  75. -----------------------------------------
  76.  
  77. The final applet API consists of the following packages:  java.lang,
  78. java.util, java.io, java.net, java.awt, java.awt.peer, java.awt.image, 
  79. and java.applet.  We and our partners are committed to supporting this API.
  80.  
  81. ----------------------------------------------------------------------
  82. IMPORTANT: Please make sure you understand the Copyright and License
  83. information (in the file named COPYRIGHT) before using this release.
  84. ----------------------------------------------------------------------
  85.  
  86.  
  87. Where do I find more information?
  88. -----------------------------------------
  89.  
  90.     This "README" file and the API documentation is the only documentation
  91.     included in this release.  The rest of the information you need is 
  92.     on our website:
  93.         
  94.         -  http://www.javasoft.com/JDK-1.0/
  95.  
  96.     It includes the following:
  97.         
  98.         -  Frequently asked questions
  99.         
  100.         -  Changes since the last release
  101.     
  102.         -  Applet examples (some of which are also in this release)
  103.  
  104.         -  API documentation 
  105.  
  106.         -  Documentation for the Java programming tools
  107.         
  108.         -  The latest Java Language Specification
  109.         
  110.         -  Known bugs in the JDK 
  111.  
  112.  
  113. If you have questions, problems, or comments:
  114. -----------------------------------------
  115.  
  116.         -  Check out the FAQ at: 
  117.             http://www.javasoft.com/JDK-1.0/faq.html
  118.  
  119.         -  Check the known bugs at: 
  120.             http://www.javasoft.com/JDK-1.0/KnownBugs-JDK.html
  121.  
  122.         -  File bug reports at: 
  123.             http://www.javasoft.com/GettingInTouch/BugReport.html
  124.  
  125.         -  The newsgroup comp.lang.java and the Java/HotJava mailing lists are
  126.             active forums for posting questions and exchanging information  with
  127.             other Java users.  See http://www.javasoft.com/mail.html for  
  128.             information on accessing the newsgroup and mailing lists.
  129.  
  130.         -  Other questions can be sent to java@java.sun.com. 
  131.         
  132.  
  133. Java Applications: an overview
  134. -----------------------------------------
  135.  
  136.     Java applications act similarly to Macintosh applications, in that
  137.     they can have a menu bar, windows, etc.  Most of the differences are
  138.     under the hood, so to speak, but they do show up in the impact that
  139.     a Java application has on your system.  Memory is particularly an
  140.     issue with Java applications.  Java is a garbage collected language,
  141.     which means that the onus of memory management is removed from the
  142.     programmer, and given to the runtime system to handle.  Periodically,
  143.     Java looks at its memory pools and deletes objects that are no longer
  144.     referenced.  Further, if the Java memory allocator cannot satisfy a
  145.     request for memory, it will exhaustively search its heap for objects
  146.     that can be freed.  (When this happens, you may see the bulldozer
  147.     "busy" cursor - please be patient!  Dig we must!)
  148.  
  149.     There are two pools of memory for a Java application, the Macintosh
  150.     Application Heap, and the Java garbage collected heap.  The
  151.     application heap can be changed by the user via the "Get Info"
  152.     command in the Finder.  The application heap is used entirely for
  153.     typical Macintosh allocations such as windows and menus.  The GC heap
  154.     is allocated in "Multifinder Temporary Memory" which is space that
  155.     is not currently used by other applications.  (If you do "About this
  156.     Macintosh" from the Finder, you'll see a label for "Largest Unused
  157.     Block".  When you launch a Java application, some of this space is
  158.     taken for the app heap, some for the GC heap.)  The GC heap can vary
  159.     in size - the smaller it is, the more time you'll spend waiting for
  160.     the garbage collector to run.  By default, the AppletViewer
  161.     application takes between 300k and 3000k of temp mem, while the
  162.     compiler requests 800k to 6000k.
  163.  
  164.     Java is a multi-threaded language - this means that while Java code
  165.     is executing (say, updating a graph display), a thread at a higher
  166.     priority (say, a user click) will interrupt that thread and execute
  167.     some other code.  When the second thread completes its task, or
  168.     starts to wait for more input, the first thread will continue where
  169.     it left off.  The Macintosh is inherently not multi-threaded,
  170.     therefore some operations will cause all threads to block, for
  171.     example, when a menu is down.  Other operations, such as selecting
  172.     text in a text field, or clicking in a button, will allow other
  173.     threads to continue.  User input is always given the utmost
  174.     priority.
  175.  
  176.     Java for Macintosh is a port of a Unix program, and there are still
  177.     some places where the infamous "stderr" and "stdout" windows will
  178.     come to front with a tidbit of trivia - most of the time this
  179.     information isn't important (unless its your own debugging output,
  180.     of course!) and you can safely close the window and move on.  If it
  181.     seems to be reporting an internal error and is persistent, you can
  182.     save the window to a file by hitting "CMD-S" while the window is
  183.     frontmost, and mail it, with a description of how to reproduce the
  184.     problem to "java-bugs@java.sun.com".  We're working to eliminate
  185.     these unnecessary interruptions as much as possible.  You can also
  186.     use the stderr and stdout windows in your own debugging; you can
  187.     even permanantly redirect their output to a file using the "Redirect"
  188.     menu items in the "Exec" menu.
  189.  
  190.  
  191. Java Compiler: the Java Bytecode Compiler
  192. -----------------------------------------
  193.  
  194.     Javac is a standalone Java compiler, with some support for minimal
  195.     user interaction.  It requires that the developer supply his or her
  196.     own editor to actually develop the program.  Some editors that can
  197.     be controlled by AppleEvents are supported directly by the
  198.     compiler.
  199.  
  200.     List of supported Text Editors:
  201.         
  202.         -  BBEdit 3.5
  203.         -  CodeWarrior IDE 7 or 8
  204.         -  SimpleText
  205.  
  206.     When the compiler starts up, a status window appears showing the
  207.     current free memory in the Java garbage collected (GC'd) heap, how
  208.     many compiles are happening simultaneously (NOTE: only one allowed
  209.     right now!) and what the compiler is currently doing.
  210.  
  211.     The compiler has the following menu options:
  212.  
  213.         -  Open: open a .java file to compile.  If the file compiles
  214.             successfully, the .class files (object files) are placed
  215.             in the directory where the source file was found.
  216.  
  217.         -  Close: close the frontmost window.  If the window was the
  218.             compiler status window, the compiler exits.
  219.  
  220.         -  Preferences: set some options for the compiler, such as
  221.             debugging information (NOTE: there is no debugger yet!)
  222.             and preferred editor.
  223.         
  224.         -  Quit: quit the compiler.  This aborts all current compilations.  
  225.  
  226.     To compile a Java program, you drop the .java file or files onto the
  227.     compiler, or select "Open" from the compilers File menu.  The compiled
  228.     output files are placed in the directory where the sources were
  229.     located.  If an error occurs when compiling, an error reporting
  230.     window will appear with a scrolling list of the text of the error,
  231.     line number, and snippet of code from where the error occurred.  If
  232.     you have the external editor listed in the Preferences dialog, double
  233.     clicking on an error, or clicking the "Edit" button will open the
  234.     file in the editor and select the line where the error occurred, if
  235.     the selected editor supports those events.  If you click the "Rebuild"
  236.     button, the files that you originally tried to compile will be recompiled.
  237.  
  238.     When the files compile successfully, they will be deposited in the
  239.     current directory as ".class" files.  You don't run applet .class
  240.     files directly; they are read by the AppletViewer program.  Depending
  241.     on how much memory you have, you might want to quit the compiler
  242.     before running the AppletViewer.
  243.  
  244.  
  245. AppletViewer: the Java Applet Runner
  246. -----------------------------------------
  247.  
  248.     AppletViewer is a drag & drop application that parses .html (hypertext
  249.     markup language) files and displays applets declared therein.  You
  250.     use it to view applets that you've developed, or if you don't have
  251.     a web browser, to view applets at other sites.
  252.  
  253.     When the AppletViewer first starts up, its status window displays the
  254.     current memory available in the Java heap, and the number of applets
  255.     that are currently running.
  256.  
  257.     The AppletViewer has the following menu options:
  258.  
  259.         -  Open URL: retrieve a URL and parse its contents, looking
  260.             for APPLET tags.
  261.  
  262.         -  Open Local: open a local .html file
  263.  
  264.         -  Properties: configure some applet properties, including byte code
  265.             verification, proxy and firewall servers, and applet access to
  266.             network resources.
  267.  
  268.         -  Quit: quit the AppletViewer
  269.         
  270.     When an applet is running, it adds an additional "Applets" menu to the menu bar:
  271.     
  272.         -  Restart: reinitialize and rerun the applet.  This doesn't reload the 
  273.        applet from the network or local disk, however.
  274.  
  275.         -  Reload: reload the applet from whence it came, and restart it.
  276.  
  277.         -  Clone: make a new copy of the applet window and restart the applet in it. 
  278.  
  279.         -  Tag: display a window with the APPLET tag that created this applet
  280.  
  281.         -  Info: show info about the applet.
  282.  
  283.         -  Edit: 
  284.  
  285.         -  Properties: same as the main Properties item
  286.  
  287.     To view an applet, you drop a .html file onto the AppletViewer icon,
  288.     open a local one from the "Open Local" menu item, or specify one via
  289.     a URL via the "Open URL" menu item.  For example, to run the MoleculeViewer
  290.     applet from the JavaSoft website, you would open the Fetch URL window,
  291.     delete the default text, and enter:
  292.     
  293.         http://www.javasoft.com/applets/applets/MoleculeViewer/example3.html
  294.  
  295.  
  296. About the APPLET tag
  297. -----------------------------------------
  298.  
  299.     The APP tag of previous releases is gone, replaced by the APPLET tag. 
  300.     Here is an example of a simple APPLET tag:
  301.  
  302.         <applet code="MyApplet.class" width=100 height=140></applet>
  303.  
  304.     This tells the viewer or browser to load the applet whose compiled
  305.     code is in MyApplet.class (in the same directory as the current HTML
  306.     document), and to set the initial size of the applet to 100 pixels
  307.     wide and 140 pixels high.
  308.  
  309.     Here's a more complex example of an APPLET tag:
  310.  
  311.         <applet codebase="http://www.javasoft.com/applets/applets/NervousText"
  312.         code="NervousText.class" width=400 height=75 align=center >
  313.         <param name="text" value="This is the Applet Viewer.">
  314.         <blockquote>
  315.         <hr>If you were using a Java-enabled browser, you would see 
  316.         dancing text instead of this paragraph.<hr>
  317.         </blockquote>
  318.         </applet>
  319.         
  320.     This tells the viewer or browser to load the applet whose compiled
  321.     code is at the URL:
  322.  
  323.         http://www.javasoft.com/applets/applets/NervousText/NervousText.class
  324.  
  325.     to set the initial size of the applet to 400x75 pixels, and to align
  326.     the applet in the center of the line.  The viewer/browser must also
  327.     set the applet's "text" attribute (which customizes the text this
  328.     applet displays) to be "This is the Applet Viewer."  If the page is
  329.     viewed by a browser that can't execute Java applets, then the browser
  330.     will ignore the APPLET and PARAM tags, displaying the HTML between
  331.     the <blockquote> and </blockquote> tags.  Java-enabled browsers
  332.     ignore that HTML.
  333.  
  334.     Here's the complete syntax for the APPLET tag:
  335.  
  336.         '<' 'APPLET'
  337.         ['CODEBASE' '=' codebaseURL]
  338.         'CODE' '=' appletFile
  339.         ['ALT' '=' alternateText]
  340.         ['NAME' '=' appletInstanceName]
  341.         'WIDTH' '=' pixels 'HEIGHT' '=' pixels
  342.         ['ALIGN' '=' alignment]
  343.         ['VSPACE' '=' pixels] ['HSPACE' '=' pixels]
  344.         '>'
  345.         ['<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>']
  346.         ['<' 'PARAM' 'NAME' '=' appletAttribute2 'VALUE' '=' value '>']
  347.         ...
  348.         [alternateHTML]
  349.         '</APPLET>'
  350.  
  351.     -  'CODEBASE' '=' codebaseURL
  352.     
  353.         This optional attribute specifies the base URL of the applet╤the
  354.         directory that contains the applet's code.  If this attribute is not
  355.         specified, then the document's URL is used.
  356.  
  357.     -  'CODE' '=' appletFile
  358.     
  359.         This required attribute gives the name of the file that contains the
  360.         applet's compiled Applet subclass.  This file is relative to the base
  361.         URL of the applet.  It cannot be absolute.
  362.  
  363.     -  'ALT' '=' alternateText
  364.     
  365.         This optional attribute specifies any text that should bedisplayed
  366.         if the browser understands the APPLET tag but can't run Java
  367.         applets.
  368.  
  369.     -  'NAME' '=' appletInstanceName
  370.  
  371.         This optional attribute specifies a name for the applet instance,
  372.         which makes it possible for applets on the same page to find (and
  373.         communicate with) each other.
  374.  
  375.     -  'WIDTH' '=' pixels 'HEIGHT' '=' pixels
  376.  
  377.         These required attributes give the initial width and height (in
  378.         pixels) of the applet display area, not counting any windows or
  379.         dialogs that the applet brings up.
  380.  
  381.     -  'ALIGN' '=' alignment
  382.     
  383.         This required attribute specifies the alignment of the applet. The
  384.         possible values of this attribute are the same as those for the IMG
  385.         tag: left, right, top, texttop, middle, absmiddle, baseline, bottom,
  386.         absbottom.
  387.  
  388.     -  'VSPACE' '=' pixels 'HSPACE' '=' pixels
  389.  
  390.         These option attributes specify the number of pixels above and below
  391.         the applet (VSPACE) and on each side of the applet (HSPACE). They're
  392.         treated the same way as the IMG tag's VSPACE and HSPACE attributes.
  393.  
  394.     -  '<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>' . . .
  395.  
  396.         This tag is the only way to specify an applet-specific attribute.
  397.         Applets access their attributes with the getParameter() method.
  398.